Wi-Fi Scan

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

功能概述

Wi-Fi Scan（Wi‑Fi扫描） 功能用于探测周围可用的Wi-Fi接入点（Access Point），并获取其详细信息（如服务集标识符SSID、基本服务集标识符BSSID、信号强度RSSI和信道等）。Wi-Fi Scan支持同步和异步两种工作模式，广泛应用于物联网设备、智能家居及网络管理等需要Wi-Fi网络环境检测的场景。

基本要素

  1. 扫描发起实体：触发Wi-Fi扫描操作的主体，通常是移动终端、物联网设备或Wi-Fi探测设备。

  2. 扫描目标（AP）：Wi-Fi扫描的对象，即周围提供无线网络服务的接入点AP，如无线路由器、热点设备。

  3. 扫描参数：控制扫描行为的配置项，包括扫描的信道范围、时长、间隔等，决定了扫描的覆盖范围与执行效率。

  4. 信号捕获单元：Wi-Fi射频前端硬件，负责接收周围AP射频信号，是AP信号采集的物理载体。

  5. 扫描结果集：Wi-Fi扫描后生成的信息集合，通常包含AP的SSID、RSSI、加密方式、BSSID等核心数据。

  6. 射频信道：Wi-Fi扫描所使用的无线频段信道，是AP与扫描实体之间的通信载体。

工作流程

Wi-Fi Scan是Wi‑Fi射频轮询探测、帧捕获、协议解析、数据规整的完整链路，依托信道快速切换与802.11帧解析实现AP信息采集，处理结果向上层业务交付的功能。具体工作流程如下：

  1. 扫描初始化：业务应用层下发扫描启动指令，Wi-Fi Scan功能完成射频单元、SPI/SDIO通信接口等硬件初始化及内部状态机初始化，完成后切换至扫描就绪状态，等待业务层配置扫描参数。

  2. 扫描参数配置：业务应用层下发扫描配置参数（信道范围、主动/被动模式、探测时长），Wi-Fi Scan功能依据配置生成信道切换时序与探测规则，预加载后续扫描执行逻辑。

  3. 射频信道探测：Wi-Fi Scan功能按预规划的信道序列切换射频链路，主动扫描向外发送探测请求帧、被动扫描监听Beacon广播，同步捕获AP的原始信号数据与RSSI。

  4. AP信息解析与整理：Wi-Fi Scan功能对捕获的信号帧进行协议解析，提取SSID/BSSID等AP信息；对同BSSID重复数据做去重处理，并按照RSSI从高到低排序，生成结构化结果集。

  5. 扫描结果反馈与缓存：Wi-Fi Scan功能经由内部交互接口向业务应用层回传AP结果集，同时在本地缓存扫描数据以支持快速二次查询，最后释放本次扫描所用临时内存，归还占用的射频硬件资源。

扫描模式分类

基于程序流程是否阻塞，扫描模式分为同步扫描和异步扫描，详情如下：

  1. 同步扫描

    • 对应函数：qosa_wifiscan_do()

    • 基本概念：调用扫描函数后，当前线程会被阻塞，直到扫描完成并返回结果后，才能继续执行后续逻辑。

    • 适用场景：对流程顺序要求严格、无需并行处理其他任务的简单单次扫描需求。

  2. 异步扫描（默认）

    • 对应函数：qosa_wifiscan_async()

    • 基本概念：调用扫描函数后，当前线程不阻塞，可继续执行其他任务；扫描完成后，结果通过预先注册的回调函数 qosa_wifiscan_register_cb() 返回。

    • 适用场景：需要并行处理多任务、避免界面卡顿的场景（如UI交互过程中触发扫描）。

典型应用场景

  • 物联网设备的Wi-Fi网络环境检测与最优网络选择。

  • 智能家居设备的网络连接与配网。

  • 网络管理工具的Wi-Fi环境分析。

  • 需要定期监控Wi-Fi网络状态的应用场景。

Wi-Fi Scan API

头文件

qosa_wifiscan.h

函数概览

函数

说明

qosa_wifiscan_open()

启用Wi-Fi Scan

qosa_wifiscan_close()

关闭Wi-Fi Scan

qosa_wifiscan_do()

开始Wi-Fi Scan同步模式扫描

qosa_wifiscan_async()

开始Wi-Fi Scan异步模式扫描

qosa_wifiscan_option_set()

配置Wi-Fi Scan扫描参数

qosa_wifiscan_get_config()

获取Wi-Fi Scan配置参数

qosa_wifiscan_register_cb()

注册异步扫描回调函数

函数详解

qosa_wifiscan_open

  • 功能描述
    启用Wi-Fi Scan。在使用其他Wi-Fi Scan功能前，必须先调用此函数启用Wi-Fi Scan。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_open(void)

  • 参数说明
    无

  • 返回值说明
    QOSA_WIFISCAN_SUCCESS：函数执行成功
    QOSA_WIFISCAN_OPEN_FAIL：Wi-Fi Scan启用异常
    QOSA_WIFISCAN_ALREADY_OPEN_ERR：Wi-Fi Scan重复启用错误
    QOSA_WIFISCAN_HW_OCCUPIED_ERR：硬件被占用
    其他值详见 qosa_wifiscan_error_e

qosa_wifiscan_close

  • 功能描述
    关闭Wi-Fi Scan。扫描完成后须调用此函数关闭Wi-Fi Scan功能，释放相关资源。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_close(void)

  • 参数说明
    无

  • 返回值说明
    QOSA_WIFISCAN_SUCCESS：函数执行成功
    其他值详见 qosa_wifiscan_error_e

qosa_wifiscan_do

  • 功能描述
    开始Wi-Fi Scan同步模式扫描。调用此函数后，当前线程会被阻塞直至扫描完成，扫描结果直接返回。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_do(
    qosa_uint16_t *p_ap_cnt,
    qosa_wifi_ap_info_t *p_ap_infos
)

  • 参数说明

参数名

输入/输出

类型

说明

p_ap_cnt

输出

qosa_uint16_t

扫描到的AP数量

p_ap_infos

输出

qosa_wifi_ap_info_t

扫描获取的每个AP信息；详见 qosa_wifi_ap_info_t

qosa_wifiscan_async

  • 功能描述
    开始Wi-Fi Scan异步模式扫描。调用此函数后，当前线程不会被阻塞，扫描结果通过注册的回调函数 qosa_wifiscan_register_cb() 返回。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_async(void)

  • 参数说明
    无

  • 返回值说明
    QOSA_WIFISCAN_SUCCESS：函数执行成功
    其他值详见 qosa_wifiscan_error_e

qosa_wifiscan_option_set

  • 功能描述
    配置Wi-Fi Scan扫描参数。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_option_set(
    qosa_wifiscan_config_t *wifiscan_config
)

  • 参数说明

参数名

输入/输出

类型

说明

wifiscan_config

输入

qosa_wifiscan_config_t

Wi-Fi Scan扫描参数；详见 qosa_wifiscan_config_t

qosa_wifiscan_get_config

  • 功能描述
    获取Wi-Fi Scan配置参数。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_get_config(
    qosa_wifiscan_config_t *wifiscan_config
)

  • 参数说明

参数名

输入/输出

类型

说明

wifiscan_config

输出

qosa_wifiscan_config_t

Wi-Fi Scan扫描参数；详见 qosa_wifiscan_config_t

  • 返回值说明
    QOSA_WIFISCAN_SUCCESS：函数执行成功
    QOSA_WIFISCAN_MEM_ADDR_NULL_ERR：内存分配失败
    其他值详见 qosa_wifiscan_error_e

qosa_wifiscan_register_cb

  • 功能描述
    注册异步扫描回调函数。当异步扫描完成时，系统会调用此回调函数返回扫描结果。

  • 函数原型

qosa_wifiscan_error_e qosa_wifiscan_register_cb(
    qosa_wifiscan_callback wifiscan_cb,
    void *user_data
)

  • 参数说明

参数名

输入/输出

类型

说明

wifiscan_cb

输入

qosa_wifiscan_callback

回调函数指针；详见 qosa_wifiscan_callback

user_data

输入

void

用户自定义数据指针

qosa_wifiscan_callback

  • 函数原型

typedef void (*qosa_wifiscan_callback)(
    void *user_data,
    qosa_wifiscan_error_e result,
    qosa_uint32_t ap_cnt,
    qosa_wifi_ap_info_t *ap_infos
)

  • 参数说明

参数名

输入/输出

类型

说明

user_data

输入

void

异步回调用户数据

result

输入

qosa_wifiscan_error_e

扫描结果码；详见 qosa_wifiscan_error_e

ap_cnt

输入

qosa_uint32_t

扫描到的AP数量

ap_infos

输入

qosa_wifi_ap_info_t

扫描获取的每个AP信息；详见 qosa_wifi_ap_info_t

  • 返回值说明
    QOSA_WIFISCAN_SUCCESS：函数执行成功
    QOSA_WIFISCAN_INVALID_PARAM_ERR：无效参数
    QOSA_WIFISCAN_ALREADY_OPEN_ERR：Wi-Fi Scan重复启用错误
    其他值详见 qosa_wifiscan_error_e

结构体定义

qosa_wifi_ap_info_t

扫描获取的每个AP信息结构体定义如下：

typedef struct
{
    qosa_uint8_t bssid[6]; 
    qosa_uint8_t channel; 
    qosa_int8_t  rssival;  
    qosa_uint8_t ssid_len;
    qosa_uint8_t ssid[33]; 
    char         reserve; 
} qosa_wifi_ap_info_t

参数

类型

说明

bssid

qosa_uint8_t

Wi-Fi AP的MAC地址

channel

qosa_uint8_t

AP工作的信道

rssival

qosa_int8_t

AP的信号强度；单位：dBm

ssid_len

qosa_uint8_t

SSID长度

ssid

qosa_uint8_t

Wi-Fi AP的SSID名称

reserve

char

预留字段

qosa_wifiscan_config_t

Wi-Fi Scan扫描参数结构体定义如下：

typedef struct
{
    qosa_uint16_t           max_ap_cnt; 
    qosa_wifiscan_channel_e channel;    
    qosa_uint8_t            scan_round; 
    qosa_uint32_t           ch_time;   
    qosa_uint32_t max_timeout;
    qosa_uint32_t scan_timeout;           
    qosa_uint8_t  wifi_priority;       
} qosa_wifiscan_config_t

参数

类型

说明

max_ap_cnt

qosa_uint16_t

Wi-Fi Scan可探测的最大AP数量

channel

qosa_wifiscan_channel_e

Wi-Fi Scan信道（1个比特位表示1个信道）；详见 qosa_wifiscan_channel_e

scan_round

qosa_uint8_t

Wi-Fi Scan扫描轮次

ch_time

qosa_uint32_t

每轮扫描中，每个信道的最长驻留扫描时长；单位：毫秒

max_timeout

qosa_uint32_t

单次Wi-Fi Scan扫描请求的最大扫描时长；单位：毫秒

scan_timeout

qosa_uint32_t

每一轮扫描的最大超时时间；单位：秒

wifi_priority

qosa_uint8_t

Wi-Fi Scan扫描优先级
0：数据优先；扫描过程中优先保障数据传输不中断
1：Wi-Fi扫描优先；优先保障扫描的信道侦听与数据捕获

枚举定义

qosa_wifiscan_error_e

Wi-Fi Scan扫描结果码枚举定义如下：

typedef enum
{
    QOSA_WIFISCAN_SUCCESS = 0,                                            
    QOSA_WIFISCAN_EXECUTE_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 1,     
    QOSA_WIFISCAN_MEM_ADDR_NULL_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 2,  
    QOSA_WIFISCAN_INVALID_PARAM_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 3,  
    QOSA_WIFISCAN_SEMAPHORE_WAIT_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 4, 
    QOSA_WIFISCAN_MUTEX_TIMEOUT_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 5,  
    QOSA_WIFISCAN_OPEN_FAIL = (QOSA_COMPONENT_WIFISCAN << 16) | 6,         
    QOSA_WIFISCAN_BUSY_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 7,          
    QOSA_WIFISCAN_ALREADY_OPEN_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 8, 
    QOSA_WIFISCAN_NOT_OPEN_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 9,      
    QOSA_WIFISCAN_HW_OCCUPIED_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 10,   
    QOSA_WIFISCAN_NO_SET_CB_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 11,   
} qosa_wifiscan_error_e

成员

说明

QOSA_WIFISCAN_SUCCESS

函数执行成功

QOSA_WIFISCAN_EXECUTE_ERR

函数执行失败

QOSA_WIFISCAN_MEM_ADDR_NULL_ERR

内存申请失败

QOSA_WIFISCAN_INVALID_PARAM_ERR

无效参数

QOSA_WIFISCAN_SEMAPHORE_WAIT_ERR

信号量等待异常

QOSA_WIFISCAN_MUTEX_TIMEOUT_ERR

互斥锁获取异常

QOSA_WIFISCAN_OPEN_FAIL

Wi-Fi Scan启用异常

QOSA_WIFISCAN_BUSY_ERR

Wi-Fi Scan忙碌，如正在进行扫描

QOSA_WIFISCAN_ALREADY_OPEN_ERR

Wi-Fi Scan重复启用错误

QOSA_WIFISCAN_NOT_OPEN_ERR

Wi-Fi Scan未启用

QOSA_WIFISCAN_HW_OCCUPIED_ERR

硬件被占用

QOSA_WIFISCAN_NO_SET_CB_ERR

未配置回调函数

qosa_wifiscan_channel_e

Wi-Fi Scan信道枚举定义如下：

typedef enum
{
    QOSA_WIFISCAN_CHANNEL_ALL_BIT = 0x1FFF,
    QOSA_WIFISCAN_CHANNEL_ONE = 0x0001,     
    QOSA_WIFISCAN_CHANNEL_TWO = 0x0002,     
    QOSA_WIFISCAN_CHANNEL_THREE = 0x0004,  
    QOSA_WIFISCAN_CHANNEL_FOUR = 0x0008,   
    QOSA_WIFISCAN_CHANNEL_FIVE = 0x0010,    
    QOSA_WIFISCAN_CHANNEL_SIX = 0x0020,     
    QOSA_WIFISCAN_CHANNEL_SEVEN = 0x0040,   
    QOSA_WIFISCAN_CHANNEL_EIGHT = 0x0080,  
    QOSA_WIFISCAN_CHANNEL_NINE = 0x0100,    
    QOSA_WIFISCAN_CHANNEL_TEN = 0x0200,    
    QOSA_WIFISCAN_CHANNEL_ELEVEN = 0x0400, 
    QOSA_WIFISCAN_CHANNEL_TWELVE = 0x0800, 
    QOSA_WIFISCAN_CHANNEL_THIRTEEN = 0x1000, 
} qosa_wifiscan_channel_e

成员

说明

QOSA_WIFISCAN_CHANNEL_ALL_BIT

扫描所有信道（位掩码组合值，涵盖信道1~13）

QOSA_WIFISCAN_CHANNEL_ONE

信道1

QOSA_WIFISCAN_CHANNEL_TWO

信道2

QOSA_WIFISCAN_CHANNEL_THREE

信道3

QOSA_WIFISCAN_CHANNEL_FOUR

信道4

QOSA_WIFISCAN_CHANNEL_FIVE

信道5

QOSA_WIFISCAN_CHANNEL_SIX

信道6

QOSA_WIFISCAN_CHANNEL_SEVEN

信道7

QOSA_WIFISCAN_CHANNEL_EIGHT

信道8

QOSA_WIFISCAN_CHANNEL_NINE

信道9

QOSA_WIFISCAN_CHANNEL_TEN

信道10

QOSA_WIFISCAN_CHANNEL_ELEVEN

信道11

QOSA_WIFISCAN_CHANNEL_TWELVE

信道12

QOSA_WIFISCAN_CHANNEL_THIRTEEN

信道13

应用逻辑流程图

同步扫描

image

异步扫描

image

示例代码

同步扫描完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/location/wifiscan/wifiscan_sync.c

异步扫描完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/location/wifiscan/wifiscan_asyn.c

开发约束与使用规范

  1. 参数配置

扫描参数 qosa_wifiscan_config_t 必须在成功调用 qosa_wifiscan_open() 前完成配置。Wi-Fi Scan启用后，再次调用 qosa_wifiscan_option_set() 将返回 QOSA_WIFISCAN_ALREADY_OPEN_ERR 报错。

  1. 设备状态管理

使用扫描接口遵循先打开、后关闭调用规范：开始扫描前必须先调用 qosa_wifiscan_open() 启用Wi-Fi Scan功能；业务结束后应调用 qosa_wifiscan_close() 关闭Wi-Fi Scan功能、释放资源。

  1. 内存管理

  • 同步扫描模式：调用者需要负责分配和释放 p_ap_infos 指向的内存空间。

  • 异步扫描模式：系统自动管理 ap_infos 内存空间，回调函数中无需手动释放。

  1. 扫描模式选择

  • 同步扫描：调用任务阻塞至扫描全流程结束，适用于需要立即获取扫描结果的场景。

  • 异步扫描：扫描结果通过回调函数返回，适用于不希望阻塞当前线程的场景。

  1. 资源竞争

Wi-Fi Scan和LTE共享射频资源，只有当LTE处于RRC Idle状态时才可正常启动Wi‑Fi扫描。

  1. 硬件占用

Wi-Fi Scan可能与蓝牙等其他无线功能共享硬件，在使用时可能遇到硬件被占用的情况。